% Notes for Hacker Within Software Carpentry Beta Testing on Documentation
% October 15, 2010

\documentclass{article}
\usepackage{verbatim}
\usepackage{amssymb}
\usepackage{graphicx}
\usepackage{longtable}
\usepackage{amsfonts}
\usepackage{amsmath}
\usepackage[usenames]{color}
\usepackage[
naturalnames = true, 
colorlinks = true, 
linkcolor = Black,
anchorcolor = Black,
citecolor = Black,
menucolor = Black,
urlcolor = Blue
]{hyperref}

\title{Software Carpentry Beta Testing}
\author{The Hacker Within
\\ \href{mailto:hacker.within.admin@gmail.com}{\texttt{hacker.within.admin@gmail.com}}
\\ \url{http://groups.google.com/group/hacker-within/}
\\ \url{http://code.google.com/p/hacker-within/}}

\setlength{\parindent}{0em}

\begin{document}
\maketitle

\section{Welcome}

Welcome to Software Carpentry Beta Testing session on automated Documentation. This training course is being taught by members of The Hacker Within, a scientific computing interest group based in the Engineering Physics Department but open to anyone. In short, the purpose of The Hacker Within is to help you be a more productive and efficient researcher and student---and to put you in contact with others trying to do likewise. \medskip

To sign up for \href{http://groups.google.com/group/hacker-within}{our Google Group} (includes an email mailing list), visit it and click ``Apply for group membership'' or \href{mailto:hacker.within.admin@gmail.com}{\texttt{email us}}. \medskip

We'll start today's session by introducing the instructor(s) ( Katy Huff ) and distributing temporary CAE user names and passwords.

\subsection{Getting these notes}

Our first order of business is to get you access to these notes and other course materials. We've placed them in a repository on our \href{http://code.google.com/p/hacker-within/}{Google Code site}. However, instead of having you visit the site and download them manually, we'll use this as an opportunity to introduce the Unix command shell and a few useful shell commands and programs. 

You may check out a read only or a committing copy of the repository. To check out a read only copy of today's session:

\begin{verbatim}
svn checkout http://hacker-within.googlecode.com/svn/trunk/sc/documentation hacker-doc 
\end{verbatim}

Alternatively, if you are registered as a committer on the googlecode site, you may check out a committing copy. This can be done either by updating a current working copy of the repository (svn update if you already have a full repo copy), or by checking out today's session:
\begin{verbatim}
~/$ svn checkout https://hacker-within.googlecode.com/svn/trunk/sc/documentation hacker-doc \
     --username YOURUSERNAME
\end{verbatim}

\subsection{OOP Example}
Today's lesson will use some source code written last year to demonstrate the hierarchical nature of programs which utilize inheritance in C++. It's not necessary that you know what that means, but it will be illuminating if you do. What you need to know about the source code is that it is in C++, the function and variable declarations are in the hpp files, and that it's set up to be built with a program called CMake.  


Now, let's navigate to the source code. Please open up the folder called ``src'' within the repository files you've just downloaded and investigate a file or two within it. (If you need help navigating the shell, please speak up.)
\begin{verbatim}
~/$ cd hacker-doc/src 
~/$ nano Forest.hpp 
\end{verbatim}

Now that it's clear we won't figure much out without any comments in the code, let's just jump in face first and run it to see what happens. 

\subsection{Building the Code}
C++ is a language that must be compiled into a machine object file in order to run. To build a file that is capable of being executed must be compiled from all of the source files in the code. We will use CMake to automate this task in a build directory outside of the source code. 
\begin{verbatim}
~/$ cd hacker-doc/
~/$ mkdir build
~/$ cd build
\end{verbatim}
To configure the makefile, we call CMake and direct it to the place where our source files are:
\begin{verbatim}
~/$ cmake ../src 
\end{verbatim}
If you type ls, you'll see that there are now new files in your build directory generated by CMake. Cool right? Well, we're going to give a talk on build systems later in the semester, so get excited. For now, cmake can remain mostly a black box except insofar as it helps us automate documentation. Now, to build the executible, we type make, calling the Makefile which will know to generate the target executible.
\begin{verbatim}
~/$ make 
\end{verbatim}
If you type ls, you'll see that we've created an executible called oop. Run it. Can you tell what it's doing from the output?
\begin{verbatim}
~/$ ./oop 
\end{verbatim}

Not really.

We have now demonstrated the problem at hand. With poor source comments, no user manual, and only minimal output, it's very difficult to understand a bunch of source files. In computational science it is unfortunately not uncommon for busy academics to neglect code comments and documentation while they write their code and they ultimately end up developing their code and sharing it in this uninformative state. 

There is simple answer.

\section{Comments in Code}
A comment is a line in code that is not compiled. It is merely there for the benefit of the reader to help with interpereting code written by other people, and, more often, ourselves. A lot can be said about comment style. We won't say anything here about it, however. Instead, this tutorial will focus on utility and substance. 

\subsection{Function Definitions}
In addition to informative function names, it is often useful to explain the arguments of a function, its behavior, and its intended uses in a comment near its declaration. You'll find a good example in the Animal class. It's called eatSomething. While the name is informative, and you can tell what information to pass that function from the arguments in its declaration, you may have to open the corresponding cpp file to find out what happens when a member of the animal class uses its eatSomething function. 

\vspace{3mm}
{\LARGE Exercise 1}
\vspace{3mm}

Please investigate the eatSomething function in the animal class, give it a useful summary, explain the arguments it takes, and what it returns, if anything. In C++, you can make comments in many ways. You may use two front slashes ``//'' for this exercise.

Now, make sure the code is okay. Return to your build directory, make and run it.

\subsection{Variable Definitions}
In addition to giving your audience the gift of informative type definitions and variable names, it is often useful to explain a variable, its units, and its intended contents in a comment near its declaration.

\vspace{3mm}
{\LARGE Exercise 2}
\vspace{3mm}

Please investigate the population variable in the animal class, give it a useful summary, explain its data structure and what information it contains. Again, you may use two front slashes ``//'' for this exercise.

Now, make sure the code is okay. Return to your build directory, make and run it.

\section{Doxygen}

\subsection{Comment Style}
You can get more functionality out of Doxygen by prescribing to a syntax that it can parse easily. While Doxygen will often pick up comments just before a function declaration even if they are merely denoted with slashes, you can control more of its behavior with specific notation. A reference for this notation is on the Doxygen website, but we will, for the sake of brevity, focus on the JavaDoc style. These utilize the asterisk thus:

\begin{align*}
 /** & \\
 * & \\ 
 * &\text{theFunction is a function that takes a type argument, arg and returns an int.}\\
 * & \\
 */ & \\
 &\text{int theFunction(type arg);}
\end{align*}

We can also make specific comments so that doxygen can interperet parts of the comment that are intended to illuminate the parameters or the return value, for instance. In this case theFunction might have a comment like:
\begin{align*}
 /** & \\
  * & \text{theFunction is a function} \\
  * & \text{@param arg is of type type} \\
  * & \\
  * & \text{@return an integer that tells us how many widgets there are}\\
  * & \\
  */ & \\
  & \text{int theFunction(type arg);}
\end{align*}

\vspace{3mm}
{\LARGE Exercise 3}
\vspace{3mm}

Now that you understand this syntax, go back and make appropriate changes the comments you made to Animal's eatSomething function and population variable.

\subsection{Configuration}
Now it's time to see what you can do with Doxygen. Go back and make the executible, with your new comments in the source files.

\begin{verbatim}
~/$ cd ~/hacker-doc/build
~/$ make
\end{verbatim}

Navigate to the doc folder and see what Doxygen has made. There is a particularly interesting html folder. Go into it and check it out.
\begin{verbatim}
~/$ cd doc
~/$ ls
~/$ cd html
~/$ firefox index.html
\end{verbatim}

In addition to finding and incorporating your comments, you'll find that Doxygen has cleverly determined the class structure of this code from the structure of the source files. Very cool. Some configuration options for the way this is displayed will be found in your doxygen.conf file in your hacker-doc/src/doc folder. This file was generated by options in the CMakeLists.txt file in your hacker-doc/src/doc folder. 

\subsection{Commented Example}
If you navigate to the folder called comments, you'll find a fully commented example of the code. Feel free to make a new build directory, call cmake, build the executible, and investigate the documentation that it's created with this small amount of extra effort.

\section{Sphinx}
Sphinx is a documentation system primarily for documenting python code. Since CAE does not have a working version of all the tools we need in order to run sphinx, I will have to neglect Sphinx in this discussion. That said, I encourage you all to go watch a great tutorial on Sphinx by Brandon Craig Rhodes at the PyCon2010 conference. When this document was written, that tutorial was being hosted on  \url{http://python.mirocommunity.org/video/1626/pycon-2010-documenting-your-pr} .
\subsection{Restructured Text}
One thing that this tutorial may discuss if we have time, however, is the input format that Sphinx relies on. Restructured text is a way to imply text formatting with ASCII text. The key is that unlike .doc, .rtf, .odf, or other such document formats, plain text documents are easy to version control, universally easy to access, and \emph{straightforward to create}. Please go to the online RST interpereter on the restructured text website to try out restructured text.

\end{document}
